Mac Format 1996 April

home *** CD-ROM | disk | FTP | other *** search

/ Mac Format 1996 April / MacFormat CD Edition MF36 (April 1996).iso / Shareware City / Developers / Tools Plus - GUI⁄Event libs / Tools Plus 2.6.1a Evaluat'n Kit / Tools Plus 2.6.1a / User Manual / 18-Miscellaneous Routines < prev next >

Wrap

INI File | 1995-04-01 | 21KB | 322 lines

[Display using Monaco 9] 18 Miscellaneous Routines `````````````````````````` This section contains some routines that simplify and enhance the programming experience. Some routines were developed specifically to replace similar parts of the Macintosh’s toolbox by providing simpler or more useful counterparts, such as Tools Plus’s DrawIcon. Other routines were written to mimic existing Macintosh user interface features to which programmers do not have access, such as the “zoom lines” that are seen when the Finder opens a document, or the standard Macintosh thermometer that indicates an application’s progress. And yet other routines are included because they were needed for the internal working of Tools Plus, and we thought they would be useful to other programmers. ------------------------------------------------------------------------ DrawIcon ```````` Draw an icon and optionally make it appear selected (darkened) or disabled (grayed). pascal void DrawIcon (short theIcon, short left, short top, Boolean EnabledFlag, Boolean SelectedFlag); procedure DrawIcon(theIcon, left, top: INTEGER; EnabledFlag, SelectedFlag: BOOLEAN); TheIcon is the icon ID that is displayed. Left and top define the top left-hand corner in the current window’s local co-ordinates where the icon is drawn. The EnabledFlag indicates if the icon is drawn as enabled or not. An enabled icon is displayed normally, whereas a disabled icon is dimmed or “grayed out.” The two constants that can be used for this flag are enabled and disabled. In nearly all cases, you will want to draw the icon as enabled. If you were to superimpose the icon with a zone from a cursor table (to make it a click-sensitive area and behave like a button), you may want to draw it as disabled to signify that it can’t be selected. The SelectedFlag indicates if the icon is to be drawn as selected or not. An unselected icon is displayed normally, whereas a selected icon is darkened. The two constants that can be used for this flag are selected and notSelected. In nearly all cases, you will want to draw the icon as notSelected. If you were to superimpose the icon with a zone from a cursor table (to make it a click-sensitive area and behave like a button), you may want to draw it as selected. Intelligent Icon Drawing ```````````````````````` The DrawIcon procedure is flexible in that it can draw color and black & white icons of various types under any conditions. It does so by using the most appropriate icon in an icon family (detailed below), depending on the number of colors displayed, and whether the icon is selected, not selected, enabled, or disabled. If your application runs on a Macintosh with multiple monitors, DrawIcon automatically draws the icon correctly, even if the icon straddles multiple screens. For this reason, DrawIcon must be placed outside any BeginUpdateScreen / EndUpdateScreen structures. Icon Family ``````````` DrawIcon can draw any of the following icon types: cicn variable size 8-bit color icon + monochrome (1-bit) equivalent + mask icl8 32x32 pixel 8-bit color icon used primarily by the Finder as your application’s icon icl4 32x32 pixel 4-bit color icon used primarily by the Finder as your application’s icon ICN# 32x32 pixel monochrome (1-bit) icon + mask used primarily by the Finder as your application’s icon ICON 32x32 pixel monochrome (1-bit) icon ics8 16x16 pixel 8-bit color icon used primarily by the Finder as your application’s icon ics4 16x16 pixel 4-bit color icon used primarily by the Finder as your application’s icon ics# 16x16 pixel monochrome (1-bit) icon + mask used primarily by the Finder as your application’s icon SICN 16x16 pixel monochrome (1-bit) icon* *Although SICN resources can contain several icons, DrawIcon only draws the first one in the resource. When a specific icon ID is shared by two or more of the icon types listed above, those related icons are called an “icon family.” The simplest example of an icon family is found in the bundle (BNDL) resource in almost all Macintosh applications. The bundle resource, usually just called a bundle, is an organization of icons used by the Finder to display your application (and its related documents) on the desk top and in folders. The icon family with an ID of 128 is usually the icon that depicts your application, where icl8 is the 8 bit icon, icl4 is the 4 bit icon, and ICN# is the 1 bit icon and mask.. DrawIcon makes use of icon families to display the best available icon. You can create and edit icons with a resource editor such as Apple’s ResEdit. When you create icons, remember to use ID numbers 128 or higher. The rest are reserved numbers. Note: To avoid icon conflicts while you are developing your application, do not create icon numbers that are used by your development environment (THINK C or THINK Pascal). THINK C and THINK Pascal sometimes supply their own icons in place of those in your resource file whenever icon numbers coincide. Icon Selection `````````````` When you specify an icon ID, DrawIcon selects an appropriate icon from the available icon family based on [1] whether or not the Macintosh has Color QuickDraw, [2] the number of colors available on the screen, and [3] whether the icon is selected or not. If Color QuickDraw is not available on the Macintosh running your application (Macintosh 512KE and Macintosh Plus only), or if your application has chosen not to use Color QuickDraw when executing the InitToolsPlus routine, DrawIcon will behave as though you are using a monochrome (black and white) monitor. When selecting an appropriate icon from the icon family (as depicted in the table below), DrawIcon first determines the number of colors available on the screen. It then checks if the icon is selected or not. Once these two criteria have been determined, DrawIcon tries to find the optimum icon type in the icon family. If the optimum icon type is not available, DrawIcon descends to the second best choice, and so on down the list. DrawIcon will use icons intended for a lesser variety of colors (i.e. from 256 to 16) if an appropriate icon isn’t available to take advantage of all the colors the screen has to offer. Icon Screen Depth Available --Icon Selection Order-- Size (in bits) Colors Not Selected Selected ```` ```````````` ````````` ```````````` ```````` Large 8 (or more) 256 (or more) icl8 icl8 cicn cicn 4 16 icl4 cicn 1 or 2 4 or ICN# ICN# black & white ICON ICON cicn† cicn† Small 8 (or more) 256 (or more) ics8 ics8 4 16 ics4 1 or 2 4 or ics# ics# black & white SICN SICN †Black and white portion only. If, for example, your application is running on an 8-bit monitor and it is trying to display a selected icon with an ID of 130, DrawIcon will always look for icon types whose ID is 130, and will first try to display an icl8. If an icl8 can’t be found, it will try to find a cicn. If neither of those icons can be found, DrawIcon will continue down the list to the icons best suited for a 4-bit monitor. Since there aren’t any in the “selected” column, it will descend again to 2-bit monitors, where it will try to find ICN#, ICON and cicn icon types. If no large icon is found, DrawIcon repeats the process for small icons by first searching for an ics8, then an ics# and SICN icon. Drawing the Icon, Selecting, Disabling, and Masking ``````````````````````````````````````````````````` All icon types are drawn within a limited square, such as the 32x32 bit ICON or 16x16 bit ics4. When the icon is displayed by DrawIcon, the icon’s image and the background within the boundaries of the square are drawn on the window. You can liken this process to using MacPaint and selecting the image by using the frame selection tool (not the lasso), then copying that image and pasting it on the destination window. As you will notice, the background is also pasted. Selecting the icon darkens it when using color or gray-scale, except for icl4 icons which can’t be darkened (in which case a substitute monochrome icon is used and darkened). On black and white monitors, the icon image is inverted (black turns to white and white turns to black). Disabling the icon overlays a gray pattern to make the icon look “grayed out.” You can specify the appearance of disabled icons by using the DefaultIconLook procedure. Each of these processes, drawing, selecting, and disabling, is done using the icon’s bounding square. If you want to limit the process to a smaller area, say, for example, to an area that is identical to an oddly shaped icon image, you can incorporate an icon mask. All drawing, selecting and disabling is performed only within the area defined by the icon mask. The cicn, ICN#, and ics# icons have integrated masks. If you use an icl8 or icl4 icon, also include an ICN# icon with the same ID, and DrawIcon will use its mask. The same applies for ics8 and ics4 icons which rely on the ics# icon for a mask. Creating Your Own Icons ``````````````````````` You can create your own icons using a resource editor, such as Apple’s ResEdit. When creating cicn, icl8 and ics8 icons with ResEdit, you have a choice of two pallets: “Apple icon colors” or “Standard 256 colors.” If your icon is going to be drawn as selected, use only the Apple icon colors, since they will guarantee that your icon can be darkened properly. Note that icons that are displayed as both selected and disabled are usually difficult to read, since simultaneously darkening and grayed out often makes the image illegible. You can also replace the system’s standard Stop, Note, and Warning icons with your own customized icons, simply by creating icons with the same IDs and including them in your application. Warning: DrawIcon must be called outside a BeginUpdateScreen / EndUpdateScreen structure. ------------------------------------------------------------------------ DefaultIconLook ``````````````` Specify the default appearance for disabled icons. pascal void DefaultIconLook (short IconSpec); procedure DefaultIconLook (IconSpec: INTEGER); The DefaultIconLook procedure specifies the appearance of disabled icons that are drawn by DrawIcon (Tools Plus also uses DrawIcon whenever it needs to draw an icon). Your application should use DefaultIconLook early on to ensure that all icons have the same appearance. If your application uses DefaultIconLook later in its execution, it will only affect icons that are drawn (or refreshed) after the change is made. IconSpec specifies the default appearance for all icons. The value for this 2-byte integer can be specified by adding a set of constants to obtain the desired result See the section below for details. Tools Plus’s picture buttons also rely on this setting to draw disabled buttons, however, each picture button can have its own settings which do not use the default. Default Appearance for Disabled Icons ````````````````````````````````````` IconSpec specifies the default appearance for all icons. The value for this 2-byte integer can be specified by adding a set of constants to obtain the desired result. You may use one of the three following dimming options: DfltIconDimBlackLtPat Overlay black color using a “light gray” (25%) pattern. DfltIconDimWhiteLtPat Overlay white color using a “light gray” (25%) pattern. DfltIconDimWhitePat Overlay white color using a “medium gray” (50%) pattern. You can also add the optional DfltIconLeaveBorder constant to preserve the icon’s border by limiting the dimming effect to an area that is 1 pixel smaller than the icon’s mask (icons that do not have a mask, such as the ‘ICON’, have an effective mask that is the icon’s entire area). If your application ever has the need to globally change the default appearance and have it instantly reflected in all the windows, add the DfltIconUpdateNow constant to the IconSpec. This option forces a doRefresh event for all open windows in your application, thereby insuring that all icons are redrawn using the new default. Picture buttons using the default settings are also updated. CONST {Disabled icons' default appearance… } DfltIconDimBlackLtPat = $01; { Overlay Black color w/ Lt Gray pat.} DfltIconDimWhiteLtPat = $02; { Overlay White color w/ Lt Gray pat.} DfltIconDimWhitePat = $04; { Overlay White color w/ Gray pattern} DfltIconLeaveBorder = $08; {Leave border when selected or } { disabled } DfltIconUpdateNow =$8000; {Update all windows with changes } ------------------------------------------------------------------------ SystemVersion ````````````` Determine what version of the System file is being used. pascal double SystemVersion(void); function SystemVersion: EXTENDED; SystemVersion determines the version of the System file being used by your application (located on your startup disk). The System file’s version is expressed as three numeric components separated by periods (i.e. 7.0.1). Because a floating-point number has a single decimal, the second period is omitted to present the decimal equivalent of 7.01. Because this routine’s source code is compiled as part of your application (it can be found in the ToolsPlus.c file for C programmers, and the ToolsPlus.p interface file for Pascal programmers), it is compiled according to your project’s compiler settings for 680x0 processor optimization and/or math co-processor optimization. Therefore, SystemVersion returns a floating-point number that can be compared to constants in your source code, such as the following example: if (SystemVersion >= 7.0) then ------------------------------------------------------------------------ Beep ```` Play the System Error sound. pascal void Beep (void); procedure Beep; Beep replaces the Macintosh toolbox’s SysBeep routine. On the Macintosh 512KE, Plus and SE, the parameter passed to the SysBeep routine specifies the duration (in clock ticks) for which the “Simple Beep” sound is played. If any other sound is selected (by the Sound control Panel), or if the sound is played on a computer other than the Macintosh 512KE, Plus and SE, the parameter is ignored. Using Beep instead of SysBeep ensures that the System Error sound is played for the correct duration regardless of the computer on which it is running. It also saves you typing, as well as two bytes per instance. ------------------------------------------------------------------------ Wait ```` Wait for a specified time. pascal void Wait (long ClockTicks); procedure Wait(ClockTicks: LONGINT); ClockTicks specifies the time that is to be waited in sixtieths of a second, or clock ticks. The Wait procedure returns to the calling application after the specified number of clock ticks have transpired. If the number is less than or equal to zero, Wait returns immediately. One example of using this procedure is when an application is first launched. After initializing Tools Plus, your application may decide to display an identification window that tells the user about the program and version number. While the window is displayed, your application can open files and obtain resources. You may decide to display the window for no less than 3 seconds, in which case you would first obtain the current number of ticks since startup from the TickCount function, display the identification window, then perform your other duties. When these tasks are completed, call TickCount again to determine how much time has transpired, then use Wait to delay for 180 ticks (3 seconds x 60 ticks), less the number of ticks that have passed since the window was first opened. Warning: Use Wait judicially because events will still be accumulating in the event queue while your application is waiting, and older events may be lost. Also, other applications won’t be getting any processing time while your application is waiting. ------------------------------------------------------------------------ ZoomLines ````````` Draw “zoom lines” from one rectangle to another. pascal void ZoomLines (Rect *OldRect, Rect *NewRect, short Zoom); procedure ZoomLines(OldRect, NewRect: RECT; ZoomType: INTEGER); The drawing of “zoom lines” creates an illusion of transition between two objects. A good example of zoom line use is in the Finder. Whenever a document, application, or disk is opened, zoom lines expand from the object. This creates an illusion that the object is opening. Zoom lines also create an apparent screen depth, since they make an object appear to zoom towards the user when it is opening, and zoom back down onto the screen when it closes. This process is called “zooming in” or “zooming out.” Another type of zoom lines is available, and that is “zooming across.” This involves a single object’s transition from one shape to another. An example of zooming across is when a window’s “zoom box” is clicked. The window changes from a user state to a standard state (or vice versa). When zooming across, the zoom lines move at a constant rate from the old co-ordinates to the new. Because no acceleration or deceleration occurs, screen depth appears to be constant. OldRect and NewRect specify the original and destination rectangles in the screen’s global co-ordinates. Transition always occurs starting at OldRect and ending at NewRect, regardless if you are zooming in, zooming out, or zooming across. ZoomType specifies the type of zoom operation being performed. The constants for this are: ZoomIn, ZoomOut and ZoomAcross. CONST {Zoom Types } ZoomIn =-1; {zoom down to an object } ZoomOut = 1; {zoom up from an object } ZoomAcross= 0; {transition from one object to another } ------------------------------------------------------------------------ DrawThermometer ``````````````` Draw the standard Macintosh progress thermometer in the current window. pascal void DrawThermometer (const Rect *DisplayRect, long Value, long Maximum); procedure DrawThermometer (DisplayRect: RECT; Value: LONGINT; Maximum: LONGINT); DrawThermometer draws the standard Macintosh progress thermometer, such as the one seen in the Finder when a file is being copied or duplicated. The thermometer is drawn according to the system that your Macintosh is running, and the settings of the monitor(s) on which the thermometer is displayed. The thermometer drawn by this routine is always similar to the one seen in the Finder. DisplayRect is the display rectangle in the current window’s local co-ordinates. If the rectangle is taller than it is wide, a vertical thermometer is created. Otherwise a horizontal thermometer is drawn. Value and Maximum are used to express the percentage completed (completed = value ÷ maximum). Progress is indicated in a left to right motion on horizontal thermometers, and from the bottom up on vertical ones. Use negative values to have the thermometer indicate progress in the reverse direction. Note: Even though DrawThermometer draws the thermometer very quickly, it may not be fast enough for applications that perform many thousands or even millions of operations during the thermometer’s progression. In that case, use the toolbox’s TickCount function to time calls to DrawThermometer at a less frequent rate, perhaps once per second. Warning: DrawThermometer must be called outside a BeginUpdateScreen/ EndUpdateScreen structure. ------------------------------------------------------------------------ min ``` Determine the minimum value of two numbers. pascal long min (long Val1, long Val2); function min(Val1, Val2: LONGINT): LONGINT; Val1 and Val2 are two numbers whose value can be of integer or longint type. The function’s value returns the lesser value of Val1 or Val2. ------------------------------------------------------------------------ max ``` Determine the maximum value of two numbers. pascal long max (long Val1, long Val2); function max(Val1, Val2: LONGINT): LONGINT; Val1 and Val2 are two numbers whose value can be of integer or longint type. The function’s value returns the greater value of Val1 or Val2.